/*!
\copyright  Copyright (c) 2019-2025 Qualcomm Technologies International, Ltd.
            All Rights Reserved.
            Qualcomm Technologies International, Ltd. Confidential and Proprietary.
\file       microphones.h
\defgroup   microphones Microphones
\ingroup    audio_domain
\brief      Component responsible for interacting with microphones and microphone user tracking
*/

#ifndef MICROPHONES_H_
#define MICROPHONES_H_

#include "microphones_config.h"

#include <audio_plugin_if.h>
#include <stream.h>

/*! @{ */

#define MICROPHONE_NONE ((uint16)0x000F)

/*! \brief Enumeration of microphone user types.

    The user type is used to aid tracking of microphone users and grant access based their priority.
    Normal and high priority users require exclusive access to a microphone resource
    and so cannot co-exist with other exclusive users. 
    Existing high priority user > new high priority user > existing normal priority user > new normal priority user
    
    Non exclusive users can access a microphone resource regardless of whether it is currently in use,
    and they do not block access from other exclusive users.
 */
typedef enum
{
    invalid_user,
    normal_priority_user,
    high_priority_user,
    non_exclusive_user,
} microphone_user_type_t;

/*! \brief Gets a specific microphone configuration.

    \param microphone_number

    \return Pointer to the specified microphone config
 */
const audio_mic_params * Microphones_GetMicrophoneConfig(uint16 microphone_number);

/*! \brief Gets the microphone id for a microphone matching the specified role.

    \param mic_role The role of the microphone to find

    \return Microphone id of the matching microphone or MICROPHONE_NONE if no matches
 */
uint16 Microphones_GetMicrophoneByRole(int mic_role);

/*! \brief Change microphone configuration.

    \param microphone_number
    \param config Pointer to config structure.
 */
void Microphones_SetMicrophoneConfig(uint16 microphone_number, audio_mic_params *config);

/*! \brief Set the sample rate of the specified microphone.

    \param microphone_number
    \param sample_rate the sample rate in Hz
    \param microphone_user_type The user type requesting to turn on the microphone
 */
void Microphones_SetMicRate(uint16 microphone_number, uint32 sample_rate, microphone_user_type_t microphone_user_type);

/*! \brief Turn on and configure the specified microphone.
           For a full configuration of the microphone use Microphones_SetMicRate to
           set the sample rate before calling TurnOnMicrophone.

    \param microphone_number
    \param microphone_user_type The user type requesting to turn on the microphone

    \return Source for the configured microphone, NULL if not available
 */
Source Microphones_TurnOnMicrophone(uint16 microphone_number, microphone_user_type_t microphone_user_type);

/*! \brief Turn off the specified microphone.

    \param microphone_number
    \param microphone_user_type The user type requesting to turn off the microphone
 */
void Microphones_TurnOffMicrophone(uint16 microphone_number, microphone_user_type_t microphone_user_type);

/*! \brief Initialises the internal state of the component.

    \param microphones_config Pointer to the microphones configuration structure.
    If NULL, one of the default configurations will be used based on the built platform. \see microphones_platform_config.h
    These default configurations serve as a starting point for the user to customise the configuration of their own product.

    The microphones configuration structure contains the number of microphones supported
    and the configuration for each microphone \see microphones_config_t
    The Microphones component will make its own copy of the configuration, the caller is not required
    to keep the configuration structure after this call.

    \important The Kymera Mic concurrency framework \see kymera_mic.c tracks its own use of microphones.
    This function is called as part of the Kymera Mic concurrency framework and calling it directly is discouraged.
    However, it is possible to call this function directly if the Kymera Mic concurrency framework is not used.
    It's also possible to call this function directly and then reinitialise the Kymera Mic concurrency framework
    but all its state will be los and care must be taken in that case to handle this scenario.

 */
void Microphones_Init(const microphones_config_t* microphones_config);

/*! \brief Returns the maximum number of microphones supported.

    \return maximum number of microphones supported
 */
uint8 Microphones_MaxSupported(void);

/*! \brief Get the source for a specific microphone

     \param microphone_number

     \return Source for the microphone, NULL if not turned on
 */
Source Microphones_GetMicrophoneSource(uint16 microphone_number);

/*! \brief Check if a microphone is in use
    \param microphone_number
    \return TRUE: Microphone is in use; FALSE: Microphone is not in use
 */
bool Microphones_IsMicrophoneInUse(uint16 microphone_number);

/*! \brief Set the number of microphones to use for voice use cases
    
    Voice use cases are e.g. SCO voice calls, LE Voice calls
    \param num_mics_for_voice number of microphones that can be used for voice use cases
 */
void Microphones_SetNumberOfMicrophonesForVoice(uint16 num_mics_for_voice);

/*! \brief Get the number of microphones to use for voice use cases
    
    Voice use cases are e.g. SCO voice calls, LE Voice calls
    \return Number of microphones that can be used for voice use cases
 */
uint16 Microphones_GetNumberOfMicrophonesForVoice(void);

/*! @} */

#endif /* MICROPHONES_H_ */
